[Experimental] Evaluate whether a subject can perform an action on a resource

[Experimental] The Evaluation API determines whether a subject is authorized to perform an action on a resource. This endpoint implements the AuthZEN Access Evaluation API specification.

Request Structure

The request requires three components:

• subject: The entity requesting access (e.g., a user or service)
• action: The operation being performed (maps to a relation in the authorization model)
• resource: The object being accessed

Each component has a type and id field, and may include optional properties for ABAC (Attribute-Based Access Control) conditions.

Response

The response contains a decision field (boolean) indicating whether access is permitted, and an optional context object with additional information such as the evaluation ID or error details.

ABAC Support

Properties on subject, action, and resource are automatically merged into the evaluation context with prefixes:

• Subject properties: subject_<property_name>
• Resource properties: resource_<property_name>
• Action properties: action_<property_name>

These merged properties can be used in conditions defined in your authorization model.

Examples

Basic authorization check

Check if user Anne can read a document:

{
  "subject": {"type": "user", "id": "anne"},
  "action": {"name": "can_read"},
  "resource": {"type": "document", "id": "roadmap"}
}

Response when authorized:

{
  "decision": true
}

Using properties for ABAC

Check access with subject and resource attributes:

{
  "subject": {
    "type": "user",
    "id": "anne",
    "properties": {"department": "engineering", "clearance_level": 3}
  },
  "action": {"name": "can_read"},
  "resource": {
    "type": "document",
    "id": "secret-project",
    "properties": {"classification": "confidential", "required_clearance": 2}
  }
}

Using request context

Provide additional context for time-based or environmental conditions:

{
  "subject": {"type": "user", "id": "bob"},
  "action": {"name": "can_access"},
  "resource": {"type": "system", "id": "production"},
  "context": {
    "current_time": "2024-01-15T14:30:00Z",
    "ip_address": "192.168.1.100",
    "is_vpn_connected": true
  }
}

Specifying authorization model

Pin the evaluation to a specific authorization model version using the Openfga-Authorization-Model-Id header:

POST /stores/{store_id}/access/v1/evaluation
Openfga-Authorization-Model-Id: 01G50QVV17PECNVAHX1GG4Y5NC

{
  "subject": {"type": "user", "id": "anne"},
  "action": {"name": "can_write"},
  "resource": {"type": "document", "id": "budget-2024"}
}